PeppermintOS Builder Comprehensive Technical Manual

Welcome to the comprehensive technical documentation for PeppermintOS Builder, the enterprise-grade, modular, dynamic, and multi-architecture toolkit for building PeppermintOS images on a Void Linux foundation.

                  _     _                      _  _     _                 
  _   ___ (_) __| |   |__  _  _  _ | |__| |___  _ __ 
 | |/ / _ \| |/ _` |  | '_ \| | | | | | / _` / _ \| '__|
 | < (_) | | (_| |  | |_) | |_| | |_| | (_| | __/ |   
 |_|\_\___/|_|\__,_|  |_.__/ \__,_|\__,_|\__,_|\___|_|   

---

Technical Documentation Index

User Guide

• Getting Started & Total Build Isolation
  • 1. Zero Host Dependency & Total Isolation Architecture
  • 2. Requirements
  • 3. Automatic Static Toolchain Resolution
  • 4. Cross-Architecture Host Helper (Optional)
  • 5. Verification & First Build Walkthrough
• Comprehensive Usage Manual & Examples
  • 1. Supported Architecture Targets Matrix
  • 2. Output Formats Explained
  • 3. Stage Seed Tarball System (Gentoo-Style Rapid ISO Builds)
  • 4. Compression Algorithms Compared
  • 4. Complete Usage Examples
• CLI Complete Technical Reference
  • Command Syntax
  • Positional Arguments
  • Presets & Editions
  • Performance & Speed Flags
  • Execution Modes & Actions
  • System & Localization Overrides
  • Security & User Management
  • Lifecycle Hooks Engine
  • Output & Formats
  • Exit Codes
• Configuration Guide & JSON Schemas
  • 1. Directory Layout & Profile Roles
  • 2. Master Manifest: global_build.json
  • 3. Architecture Profiles (configs/architectures/)
  • 4. Desktop Profiles (configs/desktops/)
  • 4. Package Bundle Profiles (configs/software/)
  • 5. Runit Service Profiles (configs/services/)
  • 6. How to Create a Brand New Desktop Profile
  • 7. Custom File Management & Scalable Overlays
  • 8. Presets & Edition Profiles (configs/presets/)
  • 9. Lifecycle Hooks Engine (configs/hooks/)
  • 10. Security Actions & Service Conflict Resolution
• Dynamic Package Rules & Resolution
  • Overview of Package Rules Engine
  • File Structure of package_rules.json
  • Deduplication & Evaluation Order
• Custom Packages & Local XBPS Repositories
  • The custom_packages/ Directory
  • Automatic Repository Indexing
  • Creating Custom Packages with xbps-src
  • Automated Python library builds
• Pepvoid — Modern Nature Collection
  • Usage
  • Sources and Prompts
  • Azores
  • Waterfall
  • Fuji
  • Mint
  • Rocky Coast
  • Forest Stream
  • Azores Cottage
  • Beach Stone
  • Beachfront
  • Butterfly
  • Dawn
  • Dusk
  • Evergreen
  • Forest Light
  • Grass Sunset
  • Ladybird
  • Meadow Light
  • Leaves Light
  • Ancient Oak
  • Coastal Sky
  • Peppermint Sunset
  • Pond Bee
  • Squirrel
  • Lighthouse
  • Sunset Tide
• Void-Builder: Hardware, Architecture & Platform Compatibility Matrix
  • 1. Executive Summary
  • 2. Supported CPU Architectures
  • 3. Dedicated Hardware Profiles & Single Board Computers (SBCs)
  • 4. Pre-Packaged Unified Presets & Desktop Environments
  • 5. Build Pipeline & Technical Highlights
  • 6. Artifact Outputs & Standards
  • 7. Quick CLI Usage Examples
• Build Isolation
• Peppermint Welcome
  • Installed files
  • Updating the bundled application
• PepFetch integration
• Suggested Packages
  • Paths and Welcome integration
  • Updating the snapshot
• PeppermintOS Software Center integration
  • Installed files
  • Updating the bundled application

Architecture & Bootloaders

• Architectural Blueprint & Engine Design
  • 1. Architectural Principles
  • 2. Complete Execution Sequence Diagram
  • 3. Class Hierarchy & Responsibilities
  • 4. Step-by-Step Pipeline Phases
• Bootloaders & Hardware Boot Manual
  • 1. Boot Architecture Overview Matrix
  • 2. PC Hybrid ISO Boot Mechanism (x86_64 / i686)
  • 3. Raspberry Pi Single-Board Computers (rpi-*)
  • 4. Pinebook Pro Laptop (pinebookpro)
  • 5. Apple Silicon Macs (asahi)
• Calamares Installer Integration
  • Architecture of Calamares Pipeline
  • Build Commands
  • Offline repository
• Python API Reference
  • Module: void_builder.core.config_loader
  • Module: void_builder.core.orchestrator
  • Module: void_builder.core.iso_engine
  • Module: void_builder.core.chroot_manager
  • Module: void_builder.core.customizer
• Troubleshooting & FAQ
  • Common Issues & Solutions
  • Log Inspection

---

Overview & Architecture Highlights

PeppermintOS Builder is an advanced Python-based toolkit designed to assemble bootable live ISO images, raw Single-Board Computer (SBC) disk images, and container rootfs archives for Void Linux. It provides a fully decoupled architecture separating configuration resolution, host toolchain management, pseudo-filesystem chroot management, system customization, and output finalization.

Key Capabilities

• 🌐 12 Hardware Architectures & Platforms: Build for x86_64, x86_64-musl, i686, aarch64, aarch64-musl, armv7l, armv7l-musl, Raspberry Pi (aarch64, armv7l, armv6l), Pinebook Pro, and Apple Silicon (Asahi).

• 🎯 Unified Presets & Flavours (-P / --preset): Ready-to-build editions (minimal, desktop-xfce, desktop-kde, desktop-gnome, rescue-sysadmin, developer, gaming).

• ⚡ High-Speed Turbo Pipeline (--fast, --tmpfs, --benchmark): Multi-threaded zstd compression level 3, fast formatting, build in memory RAM (tmpfs), and per-stage timing breakdown.

• 📦 Gentoo-Style Stage Seed Tarballs (--use-tarball, --create-tarball): Bootstraps from reusable base archives and layers delta packages in seconds.

• 🔑 Security & SSH Public Key Ingestion: Inject root passwords, lock accounts, and provision SSH keys directly into authorized_keys.

• 🪝 Lifecycle Hooks Engine: Execute customized shell scripts at pre-install, post-install, and pre-iso stages.

• 🤖 Interactive Wizard Mode (-i / --interactive): Intuitive terminal menu for step-by-step image creation.

• 🛡️ Zero Host Dependencies: Downloads verified static xbps-install.static binaries directly from Void Linux infrastructure.

• 🧾 Automated Checksums & Manifests: Automatically generates .sha256, .sha512, .md5, and .manifest.json metadata for all build artifacts.

---

Supported Target Architectures

1. x86_64: Standard 64-bit AMD/Intel PC (glibc)

2. x86_64-musl: 64-bit AMD/Intel PC with Musl C library

3. i686: 32-bit Legacy x86 PC

4. aarch64: 64-bit ARM64 Generic (glibc)

5. aarch64-musl: 64-bit ARM64 Generic (Musl)

6. armv7l: 32-bit ARMv7 Hard Float (glibc)

7. armv7l-musl: 32-bit ARMv7 Hard Float (Musl)

8. rpi-aarch64: Raspberry Pi 3/4/5 (64-bit)

9. rpi-armv7l: Raspberry Pi 2/3 (32-bit v7)

10. rpi-armv6l: Raspberry Pi 1/Zero (32-bit v6)

11. pinebookpro: Pine64 Pinebook Pro (RK3399 SoC)

12. asahi: Apple Silicon (M1/M2/M3) Asahi Linux

---

Author & Maintainer

• Developer & Lead Maintainer: Manuel Rosa (manuelsilvarosa@gmail.com)